home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / ctrsen.z / ctrsen
Encoding:
Text File  |  2002-10-03  |  9.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CTRSEN - reorder the Schur factorization of a complex matrix A =
  10.      Q*T*Q**H, so that a selected cluster of eigenvalues appears in the
  11.      leading positions on the diagonal of the upper triangular matrix T, and
  12.      the leading columns of Q form an orthonormal basis of the corresponding
  13.      right invariant subspace
  14.  
  15. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  16.      SUBROUTINE CTRSEN( JOB, COMPQ, SELECT, N, T, LDT, Q, LDQ, W, M, S, SEP,
  17.                         WORK, LWORK, INFO )
  18.  
  19.          CHARACTER      COMPQ, JOB
  20.  
  21.          INTEGER        INFO, LDQ, LDT, LWORK, M, N
  22.  
  23.          REAL           S, SEP
  24.  
  25.          LOGICAL        SELECT( * )
  26.  
  27.          COMPLEX        Q( LDQ, * ), T( LDT, * ), W( * ), WORK( * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      CTRSEN reorders the Schur factorization of a complex matrix A = Q*T*Q**H,
  44.      so that a selected cluster of eigenvalues appears in the leading
  45.      positions on the diagonal of the upper triangular matrix T, and the
  46.      leading columns of Q form an orthonormal basis of the corresponding right
  47.      invariant subspace. Optionally the routine computes the reciprocal
  48.      condition numbers of the cluster of eigenvalues and/or the invariant
  49.      subspace.
  50.  
  51.  
  52. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  53.      JOB     (input) CHARACTER*1
  54.              Specifies whether condition numbers are required for the cluster
  55.              of eigenvalues (S) or the invariant subspace (SEP):
  56.              = 'N': none;
  57.              = 'E': for eigenvalues only (S);
  58.              = 'V': for invariant subspace only (SEP);
  59.              = 'B': for both eigenvalues and invariant subspace (S and SEP).
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      COMPQ   (input) CHARACTER*1
  75.              = 'V': update the matrix Q of Schur vectors;
  76.              = 'N': do not update Q.
  77.  
  78.      SELECT  (input) LOGICAL array, dimension (N)
  79.              SELECT specifies the eigenvalues in the selected cluster. To
  80.              select the j-th eigenvalue, SELECT(j) must be set to .TRUE..
  81.  
  82.      N       (input) INTEGER
  83.              The order of the matrix T. N >= 0.
  84.  
  85.      T       (input/output) COMPLEX array, dimension (LDT,N)
  86.              On entry, the upper triangular matrix T.  On exit, T is
  87.              overwritten by the reordered matrix T, with the selected
  88.              eigenvalues as the leading diagonal elements.
  89.  
  90.      LDT     (input) INTEGER
  91.              The leading dimension of the array T. LDT >= max(1,N).
  92.  
  93.      Q       (input/output) COMPLEX array, dimension (LDQ,N)
  94.              On entry, if COMPQ = 'V', the matrix Q of Schur vectors.  On
  95.              exit, if COMPQ = 'V', Q has been postmultiplied by the unitary
  96.              transformation matrix which reorders T; the leading M columns of
  97.              Q form an orthonormal basis for the specified invariant subspace.
  98.              If COMPQ = 'N', Q is not referenced.
  99.  
  100.      LDQ     (input) INTEGER
  101.              The leading dimension of the array Q.  LDQ >= 1; and if COMPQ =
  102.              'V', LDQ >= N.
  103.  
  104.      W       (output) COMPLEX array, dimension (N)
  105.              The reordered eigenvalues of T, in the same order as they appear
  106.              on the diagonal of T.
  107.  
  108.      M       (output) INTEGER
  109.              The dimension of the specified invariant subspace.  0 <= M <= N.
  110.  
  111.      S       (output) REAL
  112.              If JOB = 'E' or 'B', S is a lower bound on the reciprocal
  113.              condition number for the selected cluster of eigenvalues.  S
  114.              cannot underestimate the true reciprocal condition number by more
  115.              than a factor of sqrt(N). If M = 0 or N, S = 1.  If JOB = 'N' or
  116.              'V', S is not referenced.
  117.  
  118.      SEP     (output) REAL
  119.              If JOB = 'V' or 'B', SEP is the estimated reciprocal condition
  120.              number of the specified invariant subspace. If M = 0 or N, SEP =
  121.              norm(T).  If JOB = 'N' or 'E', SEP is not referenced.
  122.  
  123.      WORK    (workspace/output) COMPLEX array, dimension (LWORK)
  124.              If JOB = 'N', WORK is not referenced.  Otherwise, on exit, if
  125.              INFO = 0, WORK(1) returns the optimal LWORK.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      LWORK   (input) INTEGER
  141.              The dimension of the array WORK.  If JOB = 'N', LWORK >= 1; if
  142.              JOB = 'E', LWORK = M*(N-M); if JOB = 'V' or 'B', LWORK >=
  143.              2*M*(N-M).
  144.  
  145.              If LWORK = -1, then a workspace query is assumed; the routine
  146.              only calculates the optimal size of the WORK array, returns this
  147.              value as the first entry of the WORK array, and no error message
  148.              related to LWORK is issued by XERBLA.
  149.  
  150.      INFO    (output) INTEGER
  151.              = 0:  successful exit
  152.              < 0:  if INFO = -i, the i-th argument had an illegal value
  153.  
  154. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  155.      CTRSEN first collects the selected eigenvalues by computing a unitary
  156.      transformation Z to move them to the top left corner of T. In other
  157.      words, the selected eigenvalues are the eigenvalues of T11 in:
  158.  
  159.                    Z'*T*Z = ( T11 T12 ) n1
  160.                             (  0  T22 ) n2
  161.                                n1  n2
  162.  
  163.      where N = n1+n2 and Z' means the conjugate transpose of Z. The first n1
  164.      columns of Z span the specified invariant subspace of T.
  165.  
  166.      If T has been obtained from the Schur factorization of a matrix A =
  167.      Q*T*Q', then the reordered Schur factorization of A is given by A =
  168.      (Q*Z)*(Z'*T*Z)*(Q*Z)', and the first n1 columns of Q*Z span the
  169.      corresponding invariant subspace of A.
  170.  
  171.      The reciprocal condition number of the average of the eigenvalues of T11
  172.      may be returned in S. S lies between 0 (very badly conditioned) and 1
  173.      (very well conditioned). It is computed as follows. First we compute R so
  174.      that
  175.  
  176.                             P = ( I  R ) n1
  177.                                 ( 0  0 ) n2
  178.                                   n1 n2
  179.  
  180.      is the projector on the invariant subspace associated with T11.  R is the
  181.      solution of the Sylvester equation:
  182.  
  183.                            T11*R - R*T22 = T12.
  184.  
  185.      Let F-norm(M) denote the Frobenius-norm of M and 2-norm(M) denote the
  186.      two-norm of M. Then S is computed as the lower bound
  187.  
  188.                          (1 + F-norm(R)**2)**(-1/2)
  189.  
  190.      on the reciprocal of 2-norm(P), the true reciprocal condition number.  S
  191.      cannot underestimate 1 / 2-norm(P) by more than a factor of sqrt(N).
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSEEEENNNN((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      An approximate error bound for the computed average of the eigenvalues of
  207.      T11 is
  208.  
  209.                             EPS * norm(T) / S
  210.  
  211.      where EPS is the machine precision.
  212.  
  213.      The reciprocal condition number of the right invariant subspace spanned
  214.      by the first n1 columns of Z (or of Q*Z) is returned in SEP.  SEP is
  215.      defined as the separation of T11 and T22:
  216.  
  217.                         sep( T11, T22 ) = sigma-min( C )
  218.  
  219.      where sigma-min(C) is the smallest singular value of the
  220.      n1*n2-by-n1*n2 matrix
  221.  
  222.         C  = kprod( I(n2), T11 ) - kprod( transpose(T22), I(n1) )
  223.  
  224.      I(m) is an m by m identity matrix, and kprod denotes the Kronecker
  225.      product. We estimate sigma-min(C) by the reciprocal of an estimate of the
  226.      1-norm of inverse(C). The true reciprocal 1-norm of inverse(C) cannot
  227.      differ from sigma-min(C) by more than a factor of sqrt(n1*n2).
  228.  
  229.      When SEP is small, small changes in T can cause large changes in the
  230.      invariant subspace. An approximate bound on the maximum angular error in
  231.      the computed right invariant subspace is
  232.  
  233.                          EPS * norm(T) / SEP
  234.  
  235.  
  236. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  237.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  238.  
  239.      This man page is available only online.
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.